web-utils-kit

Web Utils Kit

The web-utils-kit package provides a collection of well-tested and thoroughly documented utility functions for various web development needs. Each function adheres to a strict coding style and best practices to ensure consistency and maintainability.

Getting Started

Install the package:

npm install -S web-utils-kit

Examples

Validate a password:

import { isPasswordValid } from 'web-utils-kit';

isPasswordValid('zR<q%+r2C,&fy.SE&~.(REXTqe4K[?>G'); // true
isPasswordValid('some-weak-password'); // false

Sort a list of records:

import { sortRecords } from 'web-utils-kit';

[{ v: 1 }, { v: 2 }, { v: 3 }].sort(sortRecords('v', 'desc')); 
// [{ v: 3 }, { v: 2 }, { v: 1 }]

Execute an asynchronous function persistently:

import { retryAsyncFunction } from 'web-utils-kit';

const res = await retryAsyncFunction(
  () => fetch('https://api.example.com/user/1')
  [3, 5]
);
await res.json();
// {
//   uid: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
//   nickname: 'PythonWiz333'
// }

API Reference

Validations

isStringValid

Verifies if a value is a valid string and its length is within a range (optional).

import { isStringValid } from 'web-utils-kit';

isStringValid(''); // true
isStringValid('', 1, 5); // false
isStringValid('abcde', 1, 5); // true
isStringValid('abcdef', 1, 5); // false

isNumberValid

Verifies if a value is a valid number and is within a range (optional). The minimum value defaults to Number.MIN_SAFE_INTEGER (-9007199254740991) while the maximum value defaults to Number.MAX_SAFE_INTEGER (9007199254740991).

import { isNumberValid } from 'web-utils-kit';

isNumberValid(1); // true
isNumberValid(2, 3, 5); // false
isNumberValid(3, 3, 5); // true
isNumberValid(6, 3, 5); // false

isIntegerValid

Verifies if a value is a valid integer and is within a range (optional). If a range is not provided, it will use the properties Number.MIN_SAFE_INTEGER & Number.MAX_SAFE_INTEGER.

import { isIntegerValid } from 'web-utils-kit';

isIntegerValid(1); // true
isIntegerValid(1.5); // false

isTimestampValid

Verifies if a value is a valid unix timestamp in milliseconds. The smallest value is set for the beginning of the Unix epoch (January 1st, 1970 - 14400000) on the numeric limit established by JavaScript (9007199254740991).

import { isTimestampValid } from 'web-utils-kit';

isTimestampValid(Date.now()); // true
isTimestampValid(14399999); // false
isTimestampValid(Number.MIN_SAFE_INTEGER + 1); // false

isObjectValid

Verifies if a value is an actual object. It also validates if it has keys (optional).

import { isObjectValid } from 'web-utils-kit';

isObjectValid({}); // false
isObjectValid({}, true); // true
isObjectValid({ auth: 123, isAdmin: true }); // true
isObjectValid([0, 1, { foo: 'bar' }]); // false

isArrayValid

Verifies if a value is an array. It also validates if it has elements inside (optional).

import { isArrayValid } from 'web-utils-kit';

isArrayValid([]); // false
isArrayValid([], true); // true
isArrayValid({ auth: 123, isAdmin: true }); // false

isEmailValid

Verifies if a value is a valid email address.

import { isEmailValid } from 'web-utils-kit';

isEmailValid('[e-mail]'); // true
isEmailValid('jesus@graterol'); // false

isSlugValid

Verifies if a slug meets the following requirements:

• Accepts any Alpha Characters (lower and upper case)
• Accepts any digits
• Accepts - , . and/or _
• Meets a length range (Defaults to 2 - 16)

import { isSlugValid } from 'web-utils-kit';

isSlugValid('PythonWiz333'); // true
isSlugValid('hello-world', true); // true
isSlugValid('jesus@graterol'); // false

isPasswordValid

Verifies if a password meets the following requirements:

• Meets a length range (Defaults to 8 - 2048)
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

import { isPasswordValid } from 'web-utils-kit';

isPasswordValid('zR<q%+r2C,&fy.SE&~.(REXTqe4K[?>G'); // true
isPasswordValid('some-weak-password'); // false

isOTPSecretValid

Verifies if a value has the correct OTP Secret Format.

import { isOTPSecretValid } from 'web-utils-kit';

isOTPSecretValid('NB2RGV2KAY2CMACD'); // true

isOTPTokenValid

Verifies if a value has the correct OTP Token Format.

import { isOTPTokenValid } from 'web-utils-kit';

isOTPTokenValid('123456'); // true
isOTPTokenValid('1234567'); // false

isJWTValid

Verifies if a value has a correct JWT Format: [Base64-URL Encoded Header].[Base64-URL Encoded Payload].[Signature]

import { isJWTValid } from 'web-utils-kit';

isJWTValid('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTIzNDU2Nzg5LCJuYW1lIjoiSm9zZXBoIn0.OpOSSw7e485LOP5PrzScxHb7SR6sAOMRckfFwi4rp7o'); 
// true

isAuthorizationHeaderValid

Verifies if a value has a valid Authorization Header format based on the RFC6750. Example: Authorization: Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ

import { isAuthorizationHeaderValid } from 'web-utils-kit';

isAuthorizationHeaderValid('Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTIzNDU2Nzg5LCJuYW1lIjoiSm9zZXBoIn0.OpOSSw7e485LOP5PrzScxHb7SR6sAOMRckfFwi4rp7o'); 
// true

isSemverValid

Verifies if a value complies with semantic versioning.

import { isSemverValid } from 'web-utils-kit';

isSemverValid('1.0.0'); // true

isURLValid

Verifies if a value is a valid URL.

import { isURLValid } from 'web-utils-kit';

isURLValid('https://jesusgraterol.dev'); // true
isURLValid('jesusgraterol.dev'); // false

isUUIDValid

Verifies if a value is a valid UUID and that it matches a specific version.

import { isUUIDValid } from 'web-utils-kit';

isUUIDValid('9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d', 4); // true
isUUIDValid('01695553-c90c-705a-b56d-778dfbbd4bed', 7); // true

Transformers

prettifyNumber

Verifies if a value is a valid UUID and that it matches a specific version.

import { prettifyNumber } from 'web-utils-kit';

prettifyNumber(1000.583); // '1,000.58'
prettifyNumber(2654.69642236, { maximumFractionDigits: 8, suffix: ' BTC' }); 
// '2,654.69642236 BTC'
prettifyNumber(1000, { minimumFractionDigits: 2, prefix: '$' }); 
// '$1,000.00'

prettifyDate

Formats a date instance based on a template.

• date-short -> 12/05/2024 (Default)
• date-medium -> December 5, 2024
• date-long -> Thursday, December 5, 2024
• time-short -> 12:05 PM
• time-medium -> 12:05:20 PM
• datetime-short -> 12/5/2024, 12:05 PM
• datetime-medium -> December 5, 2024 at 12:05 PM
• datetime-long -> Thursday, December 5, 2024 at 12:05:20 PM

import { prettifyDate } from 'web-utils-kit';

prettifyDate(new Date(), 'datetime-long'); 
// 'Thursday, December 5, 2024 at 12:05:20 PM'
prettifyDate(Date.now(), 'date-medium'); 
// 'December 5, 2024'

prettifyFileSize

Formats a bytes value into a human readable format.

import { prettifyFileSize } from 'web-utils-kit';

prettifyFileSize(85545, 6); // '83.540039 kB'
prettifyFileSize(79551423); // '75.87 MB'

prettifyBadgeCount

Formats the number that will be inserted in a badge so it doesn't take too much space. If the current count is 0, it returns undefined as the badge shouldn't be displayed.

import { prettifyBadgeCount } from 'web-utils-kit';

prettifyBadgeCount(0); // undefined
prettifyBadgeCount(11); // '9+'
prettifyBadgeCount(135, 99); // '99+'

capitalizeFirst

Capitalizes the first letter of a string and returns the new value.

import { capitalizeFirst } from 'web-utils-kit';

capitalizeFirst('hello world'); // 'Hello world'

toTitleCase

Converts a string value into Title Case.

import { toTitleCase } from 'web-utils-kit';

toTitleCase('hello world'); // 'Hello World'

toSlug

Converts a string value into a slug.

import { toSlug } from 'web-utils-kit';

toSlug('HELLO WORLD!!@'); // 'hello-world'

Utils

generateUUID

Generates a UUID based on a version.

import { generateUUID } from 'web-utils-kit';

generateUUID(4); // '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
generateUUID(7); // '01695553-c90c-705a-b56d-778dfbbd4bed'

generateRandomString

Generates a string from randomly picked characters based on the length.

import { generateRandomString } from 'web-utils-kit';

generateRandomString(15); // 'IbnqwSPvZdXxVyS'

generateRandomFloat

Generates a random number (decimal) constrained by the range.

import { generateRandomFloat } from 'web-utils-kit';

generateRandomFloat(1, 100); // 67.551

generateRandomInteger

Generates a random number (integer) constrained by the range.

import { generateRandomInteger } from 'web-utils-kit';

generateRandomInteger(1, 100); // 71

generateSequence

Generates a sequence of numbers within a range based on a number of steps.

import { generateSequence } from 'web-utils-kit';

generateSequence(1, 10); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
generateSequence(1, 10, 2); // [1, 3, 5, 7, 9]

sortPrimitives

Sorts a list of primitive values based on their type and a sort direction.

import { sortPrimitives } from 'web-utils-kit';

[1, 2, 3, 4, 5].sort(sortPrimitives('asc')); 
// [1, 2, 3, 4, 5]
[1, 2, 3, 4, 5].sort(sortPrimitives('desc')); 
// [5, 4, 3, 2, 1]
['a', 'b', 'c'].sort(sortPrimitives('asc')); 
// ['a', 'b', 'c']
['a', 'b', 'c'].sort(sortPrimitives('desc')); 
// ['c', 'b', 'a']

sortRecords

Sorts a list of record values by key based on their type and a sort direction.

import { sortRecords } from 'web-utils-kit';

[{ v: 1 }, { v: 2 }, { v: 3 }].sort(sortRecords('v', 'asc')); 
// [1, 2, 3, 4, 5]
[{ v: 1 }, { v: 2 }, { v: 3 }].sort(sortRecords('v', 'desc')); 
// [{ v: 3 }, { v: 2 }, { v: 1 }]
[{ v: 'a' }, { v: 'b' }, { v: 'c' }].sort(sortRecords('v', 'asc')); 
// [{ v: 'a' }, { v: 'b' }, { v: 'c' }]
[{ v: 'a' }, { v: 'b' }, { v: 'c' }].sort(sortRecords('v', 'desc')); 
// [{ v: 'c' }, { v: 'b' }, { v: 'a' }]

shuffleArray

Creates a shallow copy of the input array and shuffles it, using a version of the Fisher-Yates algorithm.

import { shuffleArray } from 'web-utils-kit';

shuffleArray([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
// [4, 7, 5, 3,  6, 8, 9, 1, 2, 10]
shuffleArray(['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'])
// ['d', 'j', 'c', 'a', 'g', 'e', 'b', 'f', 'i', 'h']
shuffleArray([{ a: 1 }, { b: 2 }, { c: 3 }, { d: 4 }, { e: 5 }])
// [ { c: 3 }, { d: 4 }, { a: 1 }, { b: 2 }, { e: 5 } ]

pickProps

Picks a list of properties from an object and returns a new object (shallow) with the provided keys.

import { pickProps } from 'web-utils-kit';

pickProps({ a: 1, b: 2, c: 3, d: 4 }, ['b', 'd'])
// { b: 2, d: 4 }

omitProps

Omits a list of properties from an object and returns a new object (shallow) with only those keys that weren't omitted.

import { omitProps } from 'web-utils-kit';

omitProps({ a: 1, b: 2, c: 3, d: 4 }, ['b', 'd'])
// { a: 1, c: 3 }

isEqual

Compares two objects or arrays deeply and returns true if they are equals.

import { isEqual } from 'web-utils-kit';

isEqual({ a: 2, c: 5, b: 3 }, { c: 5, b: 3, a: 2 });
// true
isEqual([{ a: 1, b: 2 }], [{ b: 2, a: 1 }]);
// true

delay

Creates an asynchronous delay that resolves once the provided seconds have passed.

import { delay } from 'web-utils-kit';

await delay(3);
// ~3 seconds later

retryAsyncFunction

Executes an asynchronous function persistently, retrying on error with incremental delays defined in retryScheduleDuration (seconds).

import { retryAsyncFunction } from 'web-utils-kit';

const res = await retryAsyncFunction(
  () => fetch('https://api.example.com/user/1'),
  [3, 5],
);
await res.json();
// {
//   uid: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
//   nickname: 'PythonWiz333'
// }

Types

IUUIDVersion

The UUID versions supported by this library.

type IUUIDVersion = 4 | 7;

ISortDirection

The sort direction that can be applied to a list

type ISortDirection = 'asc' | 'desc';

INumberFormatConfig

The configuration that will be used to prettify a number.

type INumberFormatConfig = {
  minimumFractionDigits: number; // Default: 0
  maximumFractionDigits: number; // Default: 2
  prefix: string; // Default: ''
  suffix: string; // Default: ''
};

IDateTemplate

A date can be prettified by choosing a template that meets the user's requirements.

• date-short -> 12/05/2024 (Default)
• date-medium -> December 5, 2024
• date-long -> Thursday, December 5, 2024
• time-short -> 12:05 PM
• time-medium -> 12:05:20 PM
• datetime-short -> 12/5/2024, 12:05 PM
• datetime-medium -> December 5, 2024 at 12:05 PM
• datetime-long -> Thursday, December 5, 2024 at 12:05:20 PM

type IDateTemplate = 'date-short' | 'date-medium' | 'date-long' | 'time-short' | 'time-medium' | 'datetime-short' | 'datetime-medium' | 'datetime-long';

Built With

• TypeScript

Running the Tests

# integration tests
npm run test:integration

# unit tests
npm run test:unit

# benchmarks
npm run test:bench

License

MIT

Deployment

Install dependencies:

npm install

Build the library:

npm start

Publish to npm:

npm publish